中文 | English

Codex 会从多个位置读取配置细节。你的个人默认配置位于 ~/.codex/config.toml，也可以通过 .codex/config.toml 文件添加项目级覆盖项。出于安全考虑，Codex 只会在你信任该项目时加载项目配置文件。

Codex 配置文件

Codex 将用户级配置保存在 ~/.codex/config.toml。如果你想把设置限定到某个特定项目或子目录，可以在仓库中添加 .codex/config.toml 文件。

要从 Codex IDE 扩展中打开配置文件，请选择右上角的齿轮图标，然后选择 Codex Settings > Open config.toml。

CLI 和 IDE 扩展共享同一套配置层。你可以用它们来：

• 设置默认模型和 provider。
• 配置 approval policies and sandbox settings。
• 配置 MCP servers。

配置优先级

Codex 按如下顺序解析配置值（优先级从高到低）：

1. CLI flags 和 --config 覆盖项
2. Profile 的取值（来自 --profile <name>）
3. 项目配置文件：.codex/config.toml，从项目根目录一路到当前工作目录依次加载（离当前目录最近者优先；仅适用于受信任项目）
4. 用户配置：~/.codex/config.toml
5. 系统配置（如果存在）：Unix 上为 /etc/codex/config.toml
6. 内置默认值

请利用这个优先级机制：在顶层设置共享默认值，并让 profile 只关注那些确实不同的取值。

如果你把某个项目标记为不受信任，Codex 会跳过项目范围的 .codex/ 配置层（包括 .codex/config.toml），并回退到用户级、系统级和内置默认值。

关于通过 -c / --config 进行一次性覆盖（包括 TOML 的引号规则），请参阅 Advanced Config。

在受管控的机器上，你的组织也可能通过 requirements.toml 施加约束（例如，禁止 approval_policy = "never" 或 sandbox_mode = "danger-full-access"）。请参阅 Managed configuration 与 Admin-enforced requirements。

常见配置选项

下面是人们最常修改的一些选项：

默认模型

选择 Codex 在 CLI 与 IDE 中默认使用的模型。

model = "gpt-5.4"

审批提示

控制 Codex 在运行生成命令之前，何时暂停并发出询问。

approval_policy = "on-request"

有关 untrusted、on-request 和 never 三者行为差异的说明，请参阅 Run without approval prompts 和 Common sandbox and approval combinations。

沙箱级别

调整 Codex 在执行命令时拥有多少文件系统和网络访问权限。

sandbox_mode = "workspace-write"

有关各模式的具体行为（包括受保护的 .git / .codex 路径及网络默认值），请参阅 Sandbox and approvals、Protected paths in writable roots 和 Network access。

Windows 沙箱模式

当你在 Windows 原生环境中运行 Codex 时，请在 windows 表中将原生沙箱模式设为 elevated。只有在你没有管理员权限，或 elevated 初始化失败时，才应使用 unelevated。

[windows]
sandbox = "elevated"   # Recommended
# sandbox = "unelevated" # Fallback if admin permissions/setup are unavailable

对于本地任务，Codex 默认启用 web search，并从 web search cache 提供结果。该缓存是 OpenAI 维护的网页结果索引，因此 cached 模式会返回预索引结果，而不是抓取实时页面。这可以减少来自任意实时内容的 prompt injection 暴露面，但你仍应将网页结果视为不可信。如果你正在使用 --yolo 或其他 full access sandbox setting，web search 会默认返回实时结果。你可以通过 web_search 选择模式：

• "cached"（默认）从 web search cache 提供结果。
• "live" 从网页抓取最新数据（与 --search 相同）。
• "disabled" 关闭 web search 工具。

web_search = "cached"  # default; serves results from the web search cache
# web_search = "live"  # fetch the most recent data from the web (same as --search)
# web_search = "disabled"

推理强度

在模型支持的情况下，调节模型应用的推理强度。

model_reasoning_effort = "high"

沟通风格

为支持的模型设置默认沟通风格。

personality = "friendly" # or "pragmatic" or "none"

之后，你也可以在活动会话中用 /personality 覆盖它，或在使用 app-server APIs 时针对单个 thread/turn 覆盖。

命令环境

控制 Codex 会把哪些环境变量转发给它生成的命令。

[shell_environment_policy]
include_only = ["PATH", "HOME"]

日志目录

覆盖 Codex 写入本地日志文件（例如 codex-tui.log）的位置。

log_dir = "/absolute/path/to/codex-logs"

对于一次性运行，你也可以通过 CLI 设置：

codex -c log_dir=./.codex-log

Feature flags

使用 config.toml 中的 [features] 表来切换可选和实验性能力。

[features]
shell_snapshot = true           # Speed up repeated commands

支持的功能

Key	Default	Maturity	Description
apps	false	Experimental	启用 ChatGPT Apps/connectors 支持
codex_hooks	false	Under development	启用来自 hooks.json 的生命周期 hooks。参见 Hooks。
fast_mode	true	Stable	启用 Fast mode 选择以及 service_tier = "fast" 路径
multi_agent	true	Stable	启用 subagent 协作工具
personality	true	Stable	启用 personality 选择控制
shell_snapshot	true	Stable	快照 shell 环境，以加速重复命令
shell_tool	true	Stable	启用默认 shell 工具
smart_approvals	false	Experimental	将符合条件的审批请求路由给 guardian reviewer subagent
unified_exec	true except Windows	Stable	使用基于统一 PTY 的 exec 工具
undo	false	Stable	通过每轮 git ghost snapshot 启用撤销
web_search	true	Deprecated	旧版开关；请优先使用顶层 web_search 设置
web_search_cached	false	Deprecated	旧版开关；未显式设置时映射为 web_search = "cached"
web_search_request	false	Deprecated	旧版开关；未显式设置时映射为 web_search = "live"

Maturity 列使用 Experimental、Beta、Stable 等特性成熟度标签。如何理解这些标签，请参阅 Feature Maturity。

省略 feature 键即可保持其默认值。

有关当前生命周期 hooks MVP，请参阅 Hooks。

启用功能

• 在 config.toml 中，在 [features] 下添加 feature_name = true。
• 通过 CLI 运行 codex --enable feature_name。
• 若要启用多个功能，运行 codex --enable feature_a --enable feature_b。
• 若要禁用某个功能，请在 config.toml 中将该键设为 false。